
<html>
<title>surfarray - Pygame Documentation</title>
<body bgcolor=#aaeebb text=#000000 link=#331111 vlink=#331111>


<table cellpadding=0 cellspacing=0 border=0 style='border: 3px solid black;' width='100%'>
<tr>
<td bgcolor='#c2fc20' style='padding: 6px;' align=center valign=center><a href='http://www.pygame.org/'><img src='../pygame_tiny.gif' border=0 width=200 height=60></a><br><b>pygame documentation</b></td>
<td bgcolor='#6aee28' style='border-left: 3px solid black; padding: 6px;' align=center valign=center>
	||&nbsp;
	<a href=http://www.pygame.org>Pygame Home</a> &nbsp;||&nbsp;
	<a href=../index.html>Help Contents</a> &nbsp;||
	<a href=index.html>Reference Index</a> &nbsp;||
	<br>&nbsp;<br>
	
<a href=cdrom.html>Cdrom</a>&nbsp;||&nbsp;
<a href=cursors.html>Cursors</a>&nbsp;||&nbsp;
<a href=display.html>Display</a>&nbsp;||&nbsp;
<a href=draw.html>Draw</a>&nbsp;||&nbsp;
<a href=event.html>Event</a>&nbsp;||&nbsp;
<a href=font.html>Font</a>&nbsp;||&nbsp;
<a href=image.html>Image</a>&nbsp;||&nbsp;
<a href=joystick.html>Joystick</a>&nbsp;||&nbsp;
<a href=key.html>Key</a>&nbsp;||&nbsp;
<a href=mixer.html>Mixer</a>&nbsp;||&nbsp;
<a href=mouse.html>Mouse</a>&nbsp;||&nbsp;
<a href=movie.html>Movie</a>&nbsp;||&nbsp;
<a href=music.html>Music</a>&nbsp;||&nbsp;
<a href=overlay.html>Overlay</a>&nbsp;||&nbsp;
<a href=pygame.html>Pygame</a>&nbsp;||&nbsp;
<a href=rect.html>Rect</a>&nbsp;||&nbsp;
<a href=scrap.html>Scrap</a>&nbsp;||&nbsp;
<a href=sndarray.html>Sndarray</a>&nbsp;||&nbsp;
<a href=sprite.html>Sprite</a>&nbsp;||&nbsp;
<a href=surface.html>Surface</a>&nbsp;||&nbsp;
<a href=surfarray.html>Surfarray</a>&nbsp;||&nbsp;
<a href=time.html>Time</a>&nbsp;||&nbsp;
<a href=transform.html>Transform</a>
</td></tr></table>
<br>


<a name="pygame.surfarray">
<big><b>pygame.surfarray</big></b><br><ul>
  <i>pygame module for accessing surface pixel data</i><br>
<ul><small><table>
  <tr><td><a href="surfarray.html#pygame.surfarray.array2d">pygame.surfarray.array2d</a> - <font size=-1>copy pixels into a 2d array</font></td><td>copy pixels into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.pixels2d">pygame.surfarray.pixels2d</a> - <font size=-1>reference pixels into a 2d array</font></td><td>reference pixels into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.array3d">pygame.surfarray.array3d</a> - <font size=-1>copy pixels into a 3d array</font></td><td>copy pixels into a 3d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.pixels3d">pygame.surfarray.pixels3d</a> - <font size=-1>reference pixels into a 3d array</font></td><td>reference pixels into a 3d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.array_alpha">pygame.surfarray.array_alpha</a> - <font size=-1>copy pixel alphas into a 2d array</font></td><td>copy pixel alphas into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.pixels_alpha">pygame.surfarray.pixels_alpha</a> - <font size=-1>reference pixel alphas into a 2d array</font></td><td>reference pixel alphas into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.array_colorkey">pygame.surfarray.array_colorkey</a> - <font size=-1>copy the colorkey values into a 2d array</font></td><td>copy the colorkey values into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.make_surface">pygame.surfarray.make_surface</a> - <font size=-1>copy an array to a new surface</font></td><td>copy an array to a new surface</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.blit_array">pygame.surfarray.blit_array</a> - <font size=-1>blit directly from a array values</font></td><td>blit directly from a array values</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.map_array">pygame.surfarray.map_array</a> - <font size=-1>map a 3d array into a 2d array</font></td><td>map a 3d array into a 2d array</td></tr>
</table></small></ul>
<p>Functions to convert pixel data between pygame Surfaces and Numeric arrays. This module will only be available when pygame can use the external Numeric package. </p>
<p>Note, that surfarray is an optional module. It requires that Numeric is installed to be used. If not installed, an exception will be raised when it is used. eg. NotImplementedError: surfarray module not available </p>
<p>Every pixel is stored as a single integer value to represent the red, green, and blue colors. The 8bit images use a value that looks into a colormap. Pixels with higher depth use a bit packing process to place three or four values into a single number. </p>
<p>The Numeric arrays are indexed by the <tt>X</tt> axis first, followed by the <tt>Y</tt> axis. Arrays that treat the pixels as a single integer are referred to as <tt>2D</tt> arrays. This module can also separate the red, green, and blue color values into separate indices. These types of arrays are referred to as <tt>3D</tt> arrays, and the last index is 0 for red, 1 for green, and 2 for blue. </p>
<p>Numeric does not use unsigned 16bit integers, images with 16bit data will be treated as signed integers. </p>
<!--COMMENTS:pygame.surfarray--> &nbsp;<br> 


<a name="pygame.surfarray.array2d">
<big><b>pygame.surfarray.array2d</big></b><br><ul>
  <i>copy pixels into a 2d array</i><br>
  <tt>pygame.surfarray.array2d(Surface): return array</tt><br>
<p>Copy the pixels from a Surface into a <tt>2D</tt> array. The bit depth of the surface will control the size of the integer values, and will work for any type of pixel format. </p>
<p>This function will temporarily lock the Surface as pixels are copied (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a> - <font size=-1>lock the Surface memory for pixel access</font></tt> method). </p>
<!--COMMENTS:pygame.surfarray.array2d--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.pixels2d">
<big><b>pygame.surfarray.pixels2d</big></b><br><ul>
  <i>reference pixels into a 2d array</i><br>
  <tt>pygame.surfarray.pixels2d(Surface): return array</tt><br>
<p>Create a new <tt>2D</tt> array that directly references the pixel values in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. </p>
<p>Pixels from a 24-bit Surface cannot be referenced, but all other Surface bit depths can. </p>
<p>The Surface this references will remain locked for the lifetime of the array (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a> - <font size=-1>lock the Surface memory for pixel access</font></tt> method). </p>
<!--COMMENTS:pygame.surfarray.pixels2d--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.array3d">
<big><b>pygame.surfarray.array3d</big></b><br><ul>
  <i>copy pixels into a 3d array</i><br>
  <tt>pygame.surfarray.array3d(Surface): return array</tt><br>
<p>Copy the pixels from a Surface into a <tt>3D</tt> array. The bit depth of the surface will control the size of the integer values, and will work for any type of pixel format. </p>
<p>This function will temporarily lock the Surface as pixels are copied (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a> - <font size=-1>lock the Surface memory for pixel access</font></tt> method). </p>
<!--COMMENTS:pygame.surfarray.array3d--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.pixels3d">
<big><b>pygame.surfarray.pixels3d</big></b><br><ul>
  <i>reference pixels into a 3d array</i><br>
  <tt>pygame.surfarray.pixels3d(Surface): return array</tt><br>
<p>Create a new <tt>3D</tt> array that directly references the pixel values in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. </p>
<p>This will only work on Surfaces that have 24-bit or 32-bit formats. Lower pixel formats cannot be referenced. </p>
<p>The Surface this references will remain locked for the lifetime of the array (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a> - <font size=-1>lock the Surface memory for pixel access</font></tt> method). </p>
<!--COMMENTS:pygame.surfarray.pixels3d--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.array_alpha">
<big><b>pygame.surfarray.array_alpha</big></b><br><ul>
  <i>copy pixel alphas into a 2d array</i><br>
  <tt>pygame.surfarray.array_alpha(Surface): return array</tt><br>
<p>Copy the pixel alpha values (degree of transparency) from a Surface into a <tt>2D</tt> array. This will work for any type of Surface format. Surfaces without a pixel alpha will return an array with all opaque values. </p>
<p>This function will temporarily lock the Surface as pixels are copied (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a> - <font size=-1>lock the Surface memory for pixel access</font></tt> method). </p>
<!--COMMENTS:pygame.surfarray.array_alpha--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.pixels_alpha">
<big><b>pygame.surfarray.pixels_alpha</big></b><br><ul>
  <i>reference pixel alphas into a 2d array</i><br>
  <tt>pygame.surfarray.pixels_alpha(Surface): return array</tt><br>
<p>Create a new <tt>2D</tt> array that directly references the alpha values (degree of transparency) in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. </p>
<p>This can only work on 32-bit Surfaces with a per-pixel alpha value. </p>
<p>The Surface this references will remain locked for the lifetime of the array. </p>
<!--COMMENTS:pygame.surfarray.pixels_alpha--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.array_colorkey">
<big><b>pygame.surfarray.array_colorkey</big></b><br><ul>
  <i>copy the colorkey values into a 2d array</i><br>
  <tt>pygame.surfarray.array_colorkey(Surface): return array</tt><br>
<p>Create a new array with the colorkey transparency value from each pixel. If the pixel matches the colorkey it will be fully tranparent; otherwise it will be fully opaque. </p>
<p>This will work on any type of Surface format. If the image has no colorkey a solid opaque array will be returned. </p>
<p>This function will temporarily lock the Surface as pixels are copied. </p>
<!--COMMENTS:pygame.surfarray.array_colorkey--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.make_surface">
<big><b>pygame.surfarray.make_surface</big></b><br><ul>
  <i>copy an array to a new surface</i><br>
  <tt>pygame.surfarray.make_surface(array): return Surface</tt><br>
<p>Create a new Surface that best resembles the data and format on the array. The array can be <tt>2D</tt> or <tt>3D</tt> with any sized integer values. </p>
<!--COMMENTS:pygame.surfarray.make_surface--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.blit_array">
<big><b>pygame.surfarray.blit_array</big></b><br><ul>
  <i>blit directly from a array values</i><br>
  <tt>pygame.surfarray.blit_array(Surface, array): return None</tt><br>
<p>Directly copy values from an array into a Surface. This is faster than converting the array into a Surface and blitting. The array must be the same dimensions as the Surface and will completely replace all pixel values. </p>
<p>This function will temporarily lock the Surface as the new values are copied. </p>
<!--COMMENTS:pygame.surfarray.blit_array--> &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.map_array">
<big><b>pygame.surfarray.map_array</big></b><br><ul>
  <i>map a 3d array into a 2d array</i><br>
  <tt>pygame.surfarray.map_array(Surface, array3d): return array2d</tt><br>
<p>Convert a <tt>3D</tt> array into a <tt>2D</tt> array. This will use the given Surface format to control the conversion. </p>
<!--COMMENTS:pygame.surfarray.map_array--> &nbsp;<br> 
<br></ul>
<br></ul>

</body></html>
